/* Define to prevent recursive inclusion -------------------------------------*/
/* This preprocessor directive establishes an include guard mechanism to prevent */
/* multiple inclusions of the same header file during the compilation process, */
/* which would cause redefinition errors and compilation failures in the build system */
#ifndef __UART_H
#define __UART_H

/* Standard integer type inclusion for portable fixed-width integer definitions */
/* Provides uint8_t, uint16_t, etc. for consistent data type sizing across different */
/* platforms and compiler implementations, ensuring predictable memory allocation */
#include <stdint.h>

/**
 * @brief Default UART device file path for serial communication interface
 * This constant defines the default character device file in the Linux /dev directory
 * that represents the serial communication port for UART data transmission and reception
 * The path "/dev/ttyUSB1" typically corresponds to USB-to-serial adapter devices
 */
#define UART_PORT "/dev/ttyUSB1"

/**
 * @brief Maximum buffer length for UART data transmission and reception operations
 * This constant defines the size of data buffers used for storing incoming and outgoing
 * UART data, ensuring sufficient capacity for typical serial communication payloads
 * while preventing buffer overflow conditions during high-volume data transfers
 */
#define UART_BUFFER_LEN 1024

/**
 * @brief Global file descriptor for UART communication interface
 * This external variable stores the file descriptor obtained when opening the UART device,
 * which is used by all UART operations for reading from and writing to the serial port
 * The descriptor is initialized to -1 to indicate an unopened state for safety checking
 */
extern int UART_FD;

/**
 * @brief Initialize and configure UART communication interface with specified parameters
 * This function opens the specified serial port device and configures all communication
 * parameters including baud rate, data bits, parity, and stop bits for reliable data exchange
 * @param uart_port: Character pointer specifying the path to the UART device file
 *                   (e.g., "/dev/ttyS0" for hardware serial, "/dev/ttyUSB0" for USB serial)
 * @param baudRate: Unsigned 32-bit integer specifying the communication speed in bits per second
 *                  Common values include 9600, 19200, 38400, 57600, 115200 for serial communication
 * @param wordlength: Unsigned 8-bit integer specifying the number of data bits per character
 *                    Valid values are typically 7 or 8 bits, with 8 being the most common setting
 * @param parity: Character specifying the parity checking mode for error detection
 *                'n' or 'N' for no parity, 'e' or 'E' for even parity, 'o' or 'O' for odd parity
 * @param stopBit: Unsigned 8-bit integer specifying the number of stop bits for character framing
 *                 Valid values are 1 or 2 stop bits, with 1 being the most common configuration
 * @return uint8_t: Returns TRUE (1) if UART initialization and configuration completed successfully,
 *                  FALSE (0) if any step failed (device opening, parameter setting, or configuration)
 */
extern uint8_t uart_init(char *uart_port, uint32_t baudRate, uint8_t wordlength, char parity, uint8_t stopBit);

/**
 * @brief Close UART communication interface and release system resources
 * This function properly closes the UART file descriptor and releases all system resources
 * associated with the serial communication interface, ensuring clean shutdown and preventing
 * resource leaks in the operating system
 * @return uint8_t: Returns TRUE (1) if UART closure completed successfully and file descriptor
 *                  was properly released, FALSE (0) if the close operation failed or the
 *                  file descriptor was invalid
 */
extern uint8_t uart_destory(void);

/**
 * @brief Receive data from the UART communication interface
 * This function reads incoming data from the UART buffer into the provided memory location
 * using the configured file descriptor, with non-blocking behavior depending on port configuration
 * @param buffer: Pointer to memory buffer for storing received UART data. The buffer must be
 *                pre-allocated with sufficient capacity to hold the requested number of bytes
 * @param len: Unsigned 16-bit integer specifying the maximum number of bytes to read from
 *             the UART interface. This should not exceed the actual buffer size to prevent
 *             memory access violations
 * @return uint16_t: Returns the actual number of bytes successfully read from the UART interface.
 *                   This may be less than the requested length if fewer bytes are available
 *                   in the input buffer, or zero if no data is available or an error occurred
 */
extern uint16_t serial_recv(uint8_t *buffer, uint16_t len);

/**
 * @brief Transmit data through the UART communication interface
 * This function sends data from the provided buffer through the UART interface for transmission
 * to the connected serial device, using the configured file descriptor and communication parameters
 * @param buffer: Pointer to memory buffer containing the data to be transmitted through UART.
 *                The buffer must contain valid data and should not be modified during transmission
 * @param len: Unsigned 16-bit integer specifying the number of bytes to transmit through the
 *             UART interface. This should not exceed the actual buffer size to prevent reading
 *             beyond allocated memory boundaries
 * @return uint16_t: Returns the actual number of bytes successfully written to the UART interface.
 *                   This should normally equal the requested length unless a transmission error
 *                   occurred or the output buffer was full
 */
extern uint16_t serial_send(uint8_t *buffer, uint16_t len);

#endif /* __UART_H */